Jenkins 直装方式：Ubuntu 下 APT 安装与配置
直装（Direct Install）是 Jenkins 最传统的部署方式，通过操作系统的包管理器直接安装，无需额外的容器运行时。这种方式适合资源有限的服务器、无法安装 Docker 的老旧系统，以及需要精细控制系统级配置的生产环境。本文以 Ubuntu 22.04/24.04 为例，演示完整的安装和配置流程。
环境准备
直装方式需要预先安装 Java 运行环境。当前 Jenkins LTS（2.504.x）要求 Java 17 或 Java 21，不再支持 Java 11。在开始之前，确认系统已更新到最新状态。
# 更新系统包索引（Ubuntu 22.04 / 24.04 通用）
sudo apt update && sudo apt upgrade -y
# 安装 OpenJDK 21（推荐）
sudo apt install -y openjdk-21-jdk
# 验证 Java 版本
java -version
# openjdk version "21.0.x" ...
bash
安装 Jenkins
Jenkins 官方提供了 APT 仓库，通过以下步骤添加仓库并安装：
# 1. 添加 Jenkins APT 仓库的 GPG 密钥
# 注意：2025 年后 Jenkins 更新了密钥 URL，使用以下命令
sudo wget -O /usr/share/keyrings/jenkins-keyring.asc \
https://pkg.jenkins.io/debian-stable/jenkins.io-2023.key
# 2. 添加 Jenkins 仓库到 sources.list
echo "deb [signed-by=/usr/share/keyrings/jenkins-keyring.asc]" \
https://pkg.jenkins.io/debian-stable binary/ | \
sudo tee /etc/apt/sources.list.d/jenkins.list > /dev/null
# 3. 更新包索引并安装 Jenkins
sudo apt update
sudo apt install -y jenkins
bash
安装完成后，APT 会自动创建 jenkins 系统用户和 systemd 服务单元。
服务管理
Jenkins 安装后会自动注册为 systemd 服务，使用以下命令管理：
# 启动 Jenkins 服务
sudo systemctl start jenkins
# 查看服务状态
sudo systemctl status jenkins
# 设置开机自启
sudo systemctl enable jenkins
# 重启服务
sudo systemctl restart jenkins
# 查看详细日志
sudo journalctl -u jenkins --no-pager
bash
服务状态显示 active (running) 即表示 Jenkins 已正常启动。
修改默认端口（8080 -> 自定义端口）
Jenkins 默认监听 8080 端口，但该端口经常与其他服务（如 Docker 映射的 Portainer、Tomcat 等）冲突。当启动失败时，日志中会出现 Address already in use 的错误。
排查端口占用
# 检查 8080 端口占用情况
sudo netstat -anop | grep 8080
# 或使用 ss 命令（更现代）
sudo ss -tlnp | grep 8080
bash
方法一：修改 /etc/default/jenkins
这是传统的端口修改方式，编辑 Jenkins 的默认配置文件：
# 编辑配置文件
sudo vi /etc/default/jenkins
# 找到 HTTP_PORT 参数并修改
# 修改前: HTTP_PORT=8080
# 修改后: HTTP_PORT=8081
bash
修改完成后重启服务：
sudo systemctl restart jenkins
bash
注意：在某些 Ubuntu 版本上，仅修改
/etc/default/jenkins可能不生效，因为 systemd 服务单元会覆盖该配置。
方法二：通过 systemctl edit 覆盖（推荐）
这是更可靠的端口修改方式，通过 systemd 的 override 机制确保配置生效：
# 编辑 Jenkins 服务的 systemd 覆盖配置
sudo systemctl edit jenkins
# 在打开的编辑器中，在注释行之后添加以下内容：
[Service]
Environment="JENKINS_PORT=8081"
# 保存退出（Ctrl+O -> Enter -> Ctrl+X）
bash
验证覆盖配置是否正确写入：
# 查看合并后的完整服务配置
sudo systemctl cat jenkins
# 在输出末尾应能看到：
# /etc/systemd/system/jenkins.service.d/override.conf
# [Service]
# Environment="JENKINS_PORT=8081"
bash
使配置生效并重启：
# 重新加载 systemd 配置
sudo systemctl daemon-reload
# 重启 Jenkins 服务
sudo systemctl restart jenkins
# 验证新端口是否已监听
sudo ss -tlnp | grep 8081
bash
确认端口已切换后，通过浏览器访问 http://<服务器IP>:8081 即可看到 Jenkins 的初始化解锁界面。
初始化密码获取
首次访问 Jenkins 时需要输入管理员初始密码，该密码在日志和文件中均可找到：
# 方式一：从文件中读取（推荐）
sudo cat /var/lib/jenkins/secrets/initialAdminPassword
# 方式二：从启动日志中查找
sudo journalctl -u jenkins | grep -A 2 "password"
bash
日志中会输出类似以下内容：
Jenkins initial setup is required. An admin user has been created and a password generated.
Please use the following password to proceed to installation:
cf1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o
text
将该密码复制到浏览器界面的输入框中，即可进入插件安装和用户配置流程。
Troubleshooting 常见问题
问题一：服务启动失败 -- Address already in use
Job for jenkins.service failed because the control process exited with error code.
text
排查步骤：
- 使用
sudo systemctl status jenkins查看简要状态 - 使用
sudo journalctl -u jenkins查看完整日志 - 在日志中搜索
Address already in use确认端口冲突 - 使用
sudo ss -tlnp | grep <端口号>定位占用进程 - 按照「修改默认端口」一节的步骤切换端口
问题二：Java 版本不兼容
UnsupportedClassVersionError or Requires Java 17+
text
解决方案：
# 检查当前 Java 版本
java -version
# 如果版本低于 17，安装新版本
sudo apt install -y openjdk-21-jdk
# 设置默认 Java 版本
sudo update-alternatives --config java
# 选择 openjdk-21 对应的编号
# 重启 Jenkins
sudo systemctl restart jenkins
bash
问题三：GPG 密钥过期导致 apt update 失败
W: GPG error: https://pkg.jenkins.io/debian-stable ... NO_PUBKEY
text
解决方案：重新下载最新的 GPG 密钥：
sudo wget -O /usr/share/keyrings/jenkins-keyring.asc \
https://pkg.jenkins.io/debian-stable/jenkins.io-2023.key
sudo apt update
bash
问题四：防火墙阻止访问
如果 Jenkins 已启动但浏览器无法访问，检查防火墙配置：
# UFW 防火墙（Ubuntu 默认）
sudo ufw allow 8081/tcp
sudo ufw status
# iptables 防火墙
sudo iptables -L -n | grep 8081
# 云服务器安全组
# 确保在云平台控制台的安全组规则中放行对应端口
bash
完整安装流程速查
以下是从零开始在 Ubuntu 22.04/24.04 上安装 Jenkins 的完整命令序列：
# 步骤 1：系统更新 + 安装 Java 21
sudo apt update && sudo apt upgrade -y
sudo apt install -y openjdk-21-jdk
# 步骤 2：添加 Jenkins 仓库
sudo wget -O /usr/share/keyrings/jenkins-keyring.asc \
https://pkg.jenkins.io/debian-stable/jenkins.io-2023.key
echo "deb [signed-by=/usr/share/keyrings/jenkins-keyring.asc]" \
https://pkg.jenkins.io/debian-stable binary/ | \
sudo tee /etc/apt/sources.list.d/jenkins.list > /dev/null
# 步骤 3：安装 Jenkins
sudo apt update
sudo apt install -y jenkins
# 步骤 4：修改端口（可选）
sudo systemctl edit jenkins
# 添加: [Service]\nEnvironment="JENKINS_PORT=8081"
# 步骤 5：生效并启动
sudo systemctl daemon-reload
sudo systemctl start jenkins
sudo systemctl enable jenkins
# 步骤 6：获取初始密码
sudo cat /var/lib/jenkins/secrets/initialAdminPassword
# 步骤 7：浏览器访问
# http://<服务器IP>:8081（或默认 8080）
bash
↑